========================================================================== Dial-in for Linux ----------------- using getty_ps 2.0.7b plus dim 1.03 Frank Brokken e-mail: frank@icce.rug.nl ========================================================================== 1.1. Copyright -------------- The GNU General Public Licence is used with this program. I assume it's well known. If not, mail me for further details. Frank Brokken e-mail: frank@icce.rug.nl Westerhaven 16 phone: (+31) 50 63 36 88) 9718 AW Groningen (mo-vr, 9:00-17:00 MET) The Netherlands 1.2. Obtaining the dim program ------------------------------ The dim package, which is described in this document, is available at beatrix.icce.rug.nl through anonymous ftp (directory pub/unix). The program is contained in a zip called dim.X.YY.tar.gz, where X.YY is the version number. This file is availabe as dim.txt and is also contained in the archive. Also, dim has been uploaded to tsx-11.mit.edu and sunsite.unc.edu 2. PREREQUISITES ---------------- There is a number of prerequisites before the dim scheme can be implemented. 2.1. The modem -------------- First of all, the Linux box must be equipped with a modem which is capable of answering the phone and of dialling out. If you don't have a modem yet for your Linux system, but are considering buying one, go for a Hayes compatible modem. The remainder of this document shows examples for this type of modem. Second, the modem must of course be connected to a telephone. Make sure that the modem functions properly: it may be a good idea to boot under DOS and try to talk to your modem via a communications package. E.g., supposing that you have MSKERMIT (the MSDOS version of Kermit), try booting DOS, starting mskermit, and typing: set port com {this sets the COM2 (external modem) or COM4 (internal modem) port} {alternatively, use: set port com } set baud {this sets the modem speed} c {this should connect to the modem} at {this sends an attention signal to the modem} OK {modem should respond: OK} atdt 1234567 {this instructs your modem to dial (atd) using tones (t) the phone number 1234567, your modem should start dialling, use atdp for pulse dialling} NO RESPONSE or BUSY {modem response if the phone number is or NO CARRIER invalid or does not connect to a modem} or CONNECT {modem response if the phone number leads to a modem} 2.2. The modem under Linux -------------------------- The modem must function properly under Linux. The suggested modem device names are: /dev/ttyS1 and /dev/cua1 for an external modem, and /dev/ttyS3 and /dev/cua3 for an internal modem. You may need to create these devices, if you don't have them yet. The details on this are in the SERIAL.FAQ. In the remainder of this document, /dev/ttyS3 will be used in the examples; however, you may need to change this device name into /dev/ttyS1 when appropriate. Also, you may need to recompile your kernel with serial IO support. Furthermore, you will need the program setserial, version 2.02 or higher (ftp-able from tsx.11.mit.edu). The setserial program takes many parameters; such as, the uart type of the modem. E.g., I have the following line /etc/setserial /dev/ttyS3 irq 5 uart 8250 in my boot-script /etc/rc.local. This defines the uart of the modem. I have set the irq line of the modem to 5 using a dipswitch; I chose that number because that's the only irq I have left (originally, it's the irq number of the second parallel port). After configuring the modem for Linux, making sure that your kernel supports serial IO, etc., try talking to it through kermit. Use the above session example to test the working. Try calling out to a `real' system and test the reliability of the connection. 2.3 Dial-in under Linux ----------------------- Before you attempt to construct the dim procedure, you must make sure that dialling in to your Linux system works. For the dial-in you need the `new' getty or uugetty: getty_ps version 2.0.7b or higher. The sources for getty_ps can be obtained at, e.g., tsx-11.mit.edu. 2.3.1. getty_ps When constructing the new getty program, follow the instructions closely. Make sure NOT do do a "make install" right away: first, do a "make" and test the new getty as suggested. A "make install" with a non-working getty will overwrite the previous (working) version, and you might not be able to login again on your linux-box for a while... Once you have the new getty working and installed as etc/getty, adapt the following files to get dial-in working: /etc/inittab, /etc/gettydefs, /etc/default/getty.ttyS3 (the ttyS3 again referring to an internal modem; for an external modem, use ttyS1). The modifications for these files are described in the getty_ps documentation and are illustrated below. 2.3.2. /etc/inittab Here is a sample from my file inittab (see also the directory examples): s3:6:respawn:/etc/getty ttyS3 modem vt100 This line instructs init, the first program which is run under Linux, to execute /etc/getty upon startup. That program, getty, will then watch /dev/ttyS3 for activity. When eventually the modem accepts a call, getty will try to establish a connection according to two files: /etc/gettydefs and /etc/default/getty.ttyS3. The specification "respawn" in this line causes init to restart the getty process when it dies or when its subprocesses die. 2.3.3. /etc/gettydefs The file /etc/gettydefs defines the type of connection to establish. Here is a part of my /etc/gettydefs: #label # connection definitions # prompt #next #----------------------------------------------------------------- modem # B2400 CS8 # B2400 SANE -ISTRIP #login: # modem Once getty detects activity on the specified input line, it will search for the label "modem" (as mentioned in /etc/inittab) in its definition file /etc/gettydefs. That label occurs here, and instructs getty to try to establish a 2400 baud connection. In my case, this is a fixed baud rate, you might want to change that if you want to use an adaptable baud rate setting. See the SERIAL-FAQ for details. 2.3.4. /etc/default/getty.ttyS3 The file /etc/default/getty.ttyS3 is needed for the `new' getty program. The previous getty, often still distributed with SLS, does not use this file. The file therefore has to be created. Here is a sample of the file /etc/default/getty.ttyS3: SYSTEM= VERSION=/proc/version LOGIN=/bin/login ISSUE=/etc/issue CLEAR=NO HANGUP=YES INIT="" ATH\r OK ATZ\r OK ATS0=1&C1&D3&W\r OK TIMEOUT=60 CONNECT="" CONNECT This file defines the following actions: (a) The first four lines define text information, to be displayed during the login process. Refer to the getty_ps information for the meaning of these lines; e.g., the line LOGIN=/bin/login defines the program which is used to log in a user. (b) The lines CLEAR=NO and HANGUP=YES define the way that getty handles the modem. (c) The line INIT="" ATH\r OK ATZ\r OK ATS0=1&C1&D3&W\r OK consists of strings, which are in turn either expected by getty to be read from the modem line, or which are sent to the modem. The INIT label tells getty to execute this sequence upon startup. The sequence can be read as follows: - Getty should wait for no special string on the modem line (""). - Getty should then send the string "ATH", followed by a carriage-return, to the modem. This hangs up the phone line. - Getty should then wait for the string OK to appear on the modem line; that is the modem's response. - Getty should then send "ATZ", followed by a carriage-return. This re-initializes the modem. - Getty should then wait for an OK. - Getty will then send "ATS0=1", followed by a carriage-return. This will instruct the modem to answer the phone on the first incoming ring. &C1 sets the carrier detect signal only when the remote carrier is present. &D3 forces a hangup of the line, and resets the modem, after an ON-to-OFF Data Terminal Ready transition. &W writes the active configuration in the profile to be used by default. (&W0&W1 would store the active profile in both nonvolatile profile memories, that would be ok too). The &C1&D3 were added after experiencing problems with the modem configuration after switching off the computer (in my case: the modem too, as it's an internal one). Apparently the &C1&D3 settings weren't kept, causing the modem to spawn login constantly. The &C1&D3 addition cured the problem. - Getty should again wait for an OK from the modem. Please note that the AT commands, which are sent to the modem, apply to my `Hayes-compatible' modem. Be sure to check your modem documentation for the exact syntax applying to your modem when using these commands for your own setup. (d) The TIMEOUT specification instructs getty to break the connection when the user waits longer than 60 seconds before logging in. (f) The line CONNECT="" CONNECT defines a chat-sequence to be performed after the modem has auto-answered the phone. The sequence can be read as follows: - Getty is instructed not to wait for specific information (""). - Then getty waits for the string CONNECT, whereupon the login process starts. 2.3.5. The modem-setup itself ----------------------------- The modem itself should be configured as follows: (profile 1 is identical to profile 0: I left it out. No phone-numbers are configured, also left out). ---------------------------------------------------------------------- ACTIVE PROFILE: B1 E1 L3 M3 Q0 V1 X4 Y1 &C1 &D3 &G0 &J1 &L0 &P1 &Q0 &R1 &S1 &X0 &Y0 S00:000 S01:000 S02:043 S03:013 S04:010 S05:008 S06:002 S07:030 S08:002 S09:006 S10:014 S12:050 S14:AAH S16:00H S18:000 S21:FFH S22:FFH S23:17H S25:005 S26:001 S27:40H STORED PROFILE 0: B1 E1 L3 M3 Q0 V1 X4 Y1 &C1 &D3 &G0 &J1 &L0 &P1 &Q0 &R1 &S1 &X0 S00:000 S14:AAH S18:000 S21:FFH S22:FFH S23:17H S25:005 S26:001 S27:40H ---------------------------------------------------------------------- Several things are worth noting: 1. Contrary to the SERIAL-FAQ, the modem is *not* shut up at all: command echoing is on (E1), and the modem sends responses (Q0). In fact, by shutting up the modem I had a completely failing INIT chat-sequence in the original setup, as getty never got anything back from the modem. 2. &C1: Carrier Detect Signal is only ON when a remote carrier signal is present. This is in line with the SERIAL-FAQ. 3. &D3: Once the connection is broken (On to Off Data Terminal Ready transition), the modem will hangup the line, reset, and return to command-mode. Again, in line with the SERIAL-FAQ. After installing getty_ps and modifying all necessary files, you should have the dial-in protocol established. Test the dialling in before attempting the next step: installing dim. 4. GETTY DEFINITION FILES ------------------------- Dim uses two getty definition files. These files are /conf/callback/getty.ttyS3.org and /conf/callback/getty.ttyS3.dim. (The directory specification 'conf/callback' is a leftover from Karel Kubat's callback system. His directory slection has been accepted unaltered by dim. It can of course be changed to another name of your liking). The first of these files, with the extension .org, is the file which causes getty to accept incoming calls. This file is used in dim's -reset command, and has already been described before: SYSTEM= VERSION=/proc/version LOGIN=/bin/login ISSUE=/etc/issue CLEAR=NO HANGUP=YES INIT="" ATH\r OK ATZ\r OK ATS0=1&C1&D3&W\r OK TIMEOUT=60 CONNECT="" CONNECT The file /conf/callback/getty.ttyS3.dis will diable the autoanswering facility of the modem. It contains but one line: INIT="" ATH\r OK ATZ\r OK ATS0=0&C1&D3&W\r OK Via this initialization the modem is instructed not to react to incoming calls. The command ATS0=0 disables the auto-answering. 5. INSTALLING DIM ----------------- Before unpacking the zip containing the sources, create an appropriate directory (e.g., /usr/local/src/dim). Move the archive to this directory and unpack it. Archives in the form .zip can be unpacked using "unzip ". 5.1. The file src/config.h -------------------------- The pathnames used by the dim program use the directory /conf/callback. If you dislike this name, edit src/config.h and substitute your favorite name. Note however that it may be a good idea to place all configuration files into a directory which is only readable by root. In the following discussion it is assumed that the default name /conf/callback is used. dim assumes that you are using an internal modem, pointed to by the device /dev/ttyS3. If you are using an external modem, change all occurrences of "ttyS3" into "ttyS1" in the file src/config.h. Furthermore, you may want or need to change the following strings or defines in src/config.h: TMPGETTY - this filename is used as a temporary file. dim deletes this file after operation. Default: /tmp/getty.ttyS3.tmp. LOGIN - the original login program. Default: /bin/login. ERRLOG - the logfile where cblogin logs fatal errors. Default: /usr/adm/dim.log. PANICLOG - the file where cblogin writes fatal errors, when ERRLOG cannot be written. Default: /dev/console. EMAIL - e-mail address which is displayed to the dialling in user when cblogin cannot proceed. You can leave this string undefined if you do not wish any e-mail address shown. The default is my e-mail address; please change the string or undefine it, or my name will appear in your modem's login screen. DISABLEGETTY - Define this filename if you want the system administrator's tool cbstat to be able to disable the modem. This file must then contain a getty definition which disables the modem. 5.2. Building dim ----------------- First, create the directory for the configuration files of dim. E.g., if this directory should be the default conf/callback, do a: mkdir -p /conf/callback (cd /conf; chmod 700 dim) This will make the directory readable by root only. If you have Icmake, look at the file "build". Modify the define dimDIR (default: /conf/callback) if you do not want to use this name as the basic dim directory. Modify the define BINDIR if you wish an installation of this program into an other directory. After modifying the file "build", do a "./build install". If you do not have Icmake, get it. Icmake is a powerful program maintenance tool and a script language, and is available at tsx-11.mit.edu (directory pub/linux/sources/usr.bin) or at beatrix.icce.rug.nl (directory pub/unix). The file icmake.doc explains how to install Icmake. If you cannot get Icmake, chdir to the directory src and do: (cd dim ; gcc -c *.c) gcc -o dim/dim dim/*.o mv dim/dim /usr/local/bin chmod 700 /usr/local/bin/dim Note that dim is only readable and executable by root. 5.3. The program dim -------------------- The program dim, which is installed by default to /usr/local/bin, is a small tool to either see what the dim setup is doing, or to force the modem into auto answering mode or not. The program should be readable and executable by root only, since it is only an administrator's tool. When dim is invoked without arguments, usage information is shown on the screen. The actions of dim are further discussed below: dim -disable: This option can only be used when the define DISABLEGETTY is used during the compilation and installation of the package. The file /conf/callback/getty.ttyS3.dis is copied to /etc/default/getty.ttyS3: the disable-file should contain commands to disable the modem. Having copied this file, getty (for the modem-line) is killed, and is immediately restarted again by init, using the new getty.ttyS3 file. dim -enable: This forces the modem into its auto-answer state. The getty definition file which allows only dial-in, /conf/callback/getty.ttyS3.org, is copied to /etc/default/getty.ttyS3. Then getty is killed, immediately to be restarted again, using the new getty.ttyS3, by init. dim -file: This shows the current getty definition file /etc/default/getty.ttyS3, stripped of comment lines etc. dim -wake: This tries to wake up init by sending a SIGHUP. This will also generate a kernel message: '/etc/initrunlvl not found', which may safely be ignored. The message is logged on the file /usr/adm/syslog (i.e., on my linux-box) 6. DIM AND CALLBACK ------------------- Karel Kubat's callback program and dim resemble each other in many ways. Questions regarding callback should be sent to karel@icce.rug.nl. Questions regarding dim can be sent to me: frank@icce.rug.nl 7. INCOMING CALLS ----------------- At some point in time, when dim is installed, you might want to answer an incoming call via the modem, rather than via getty. I had some problems initially in getting that part of the story running smoothly. Here's how I do it now: - When you know an incoming call is about to arrive, start kermit. - Then, if the call arrives, kermit rather than getty will catch the call. - The modem beeps and shreeks and falls silent. *THAT* is the time to enter: - c - Now you're connected to the incoming call via kermit, and you can, e.g., login. However, if you know there may be incoming calls but you don't want to accept them, then you will probably have given the command dim -disable Why would you do that? Well, I have my linux-box at the office call my linux-box at home every evening between 18:00 and 20:00, every 15". Usually within that time-block I want to login at the office's linux-box. Not every 15", so I don't want the modem to accept the call at that time. But, if the modem has been switched off (dim -disable) I can start kermit allright, but it won't take the call since the modem was switched off. This is cured by the following 'modem.kermrc' file which I pass to kermit when kermit is started, i.e., I give the command kermit modem.kermrc The modem.kermrc file contains: ---------------------------------------- set line /dev/ttyS3 set speed 2400 set modem hayes set dial dial-command ATDT%s\{13} set prompt [modem] kermit> set file type bin set file name lit output ats0=1\13 ---------------------------------------- The last line here is the interesting one: it enables auto-answering when kermit is started. So, if dim -disable has been given, I can start kermit and the modem will now accept incoming calls, due to the enabling of the auto-answering. Note that when kermit is done, it resets the modem again, which may or may not what you want. At some point you might want to do an explicit dim -enable after the kermit session. 8. HISTORY ---------- 1.00: Initial release. One program, dim, documentation, and example files. 1.01: Appending &C1&D3&W to the INIT chat-sequences to prevent constantly respawning of login. 1.02: Change in the description only. A section on answering incoming calls 1.03: Changes in the description and file organization, related to sunsite and tsx-11 uploads. Icmake binaries are part of the distribution.